Skip to content

Glues your website's sidebars, making them permanently visible while scrolling.

License

Notifications You must be signed in to change notification settings

WeCodePixels/theia-sticky-sidebar

Repository files navigation

Theia Sticky Sidebar

A lightweight JavaScript (TypeScript) library that glues your website's sidebars (or any vertical column), making them permanently visible when scrolling up and down. Useful when a sidebar is too tall or too short compared to the rest of the content. Works with virtually any design and supports multiple sidebars.

Check out some examples:

ESLint Playwright and SonarQube

Install

Package Manager Install Command
NPM npm add theia-sticky-sidebar
Yarn yarn add theia-sticky-sidebar
PNPM pnpm add theia-sticky-sidebar

Usage

Your website's HTML structure has to be similar to this in order to work:

<div>
    <div class="content">
        <div class="theiaStickySidebar">
            ...
        </div>
    </div>
    <div class="sidebar">
        <div class="theiaStickySidebar">
            ...
        </div>
    </div>
</div>

Note that the inner theiaStickySidebar divs are optional, but highly recommended. If you don't supply them yourself, they will be created for you, but this can be problematic: ads or iframes will be moved around and may be loaded twice.

For the above example, you can use the following code:

JavaScript

<script src="dist/theia-sticky-sidebar.min.js"></script>

<script>
    document.addEventListener('DOMContentLoaded', function () {
        const tss = new TheiaStickySidebar({
            elements: '.content, .sidebar',
            additionalMarginTop: 30
        });
    });
</script>

TypeScript

import {TheiaStickySidebar} from "theia-sticky-sidebar/dist/theia-sticky-sidebar";

document.addEventListener('DOMContentLoaded', function () {
    const tss = new TheiaStickySidebar({
        elements: '.content, .sidebar',
        additionalMarginTop: 30
    });
});

React

This example uses just one sidebar.

import React, {useEffect, useRef} from "react";
import {TheiaStickySidebar} from "theia-sticky-sidebar/dist/theia-sticky-sidebar";

export const MyComponent = () => {
    const sidebarRef = useRef<HTMLDivElement>(null);
    const theiaStickySidebarRef = useRef<TheiaStickySidebar>();

    useEffect(() => {
        // Activate sticky sidebar once the component is mounted.
        theiaStickySidebarRef.current = new TheiaStickySidebar({
            elements: sidebarRef.current!,
            additionalMarginTop: 30
        });

        // Gracefully remove the sidebar once the component is unmounted.
        return () => {
            theiaStickySidebarRef.current!.unbind();
        };
    }, []);

    return <div>
        <div class="content">
            ...
        </div>
        <div class="sidebar" ref={sidebarRef}>
            <div class="theiaStickySidebar">
                ...
            </div>
        </div>
    </div>
}

Settings

Setting Type Description
elements string | HTMLElement | Array<HTMLElement> Required. Can be a simple string selector, like .my-sidebar, or .my-sidebar-1, .my-sidebar-2. Or, it can be a DOM element, like document.querySelector('.my-sidebar'). Or, it can be an array of DOM elements.
containerSelector string Selector for the sidebar's container element. If not specified, it defaults to the sidebar's parent.
additionalMarginTop number An additional top margin in pixels. Defaults to 0.
additionalMarginBottom number An additional bottom margin in pixels. Defaults to 0.
updateSidebarHeight boolean Updates the sidebar's height. Use this if the background isn't showing properly, for example. Defaults to true.
minWidth number The sidebar returns to normal if its width is below this value. Useful for responsive designs. Defaults to 0.
disableOnResponsiveLayouts boolean Try to detect responsive layouts automatically and disable the sticky functionality on smaller screens. More exactly, it detects when the container and the sidebar are moved one on top of the other, instead of showing up side-by-side. Defaults to true.
defaultPosition string The sidebar must have a non-static position, as the inner sticky-sidebar uses position: absolute. Defaults to relative.

Development

If you want to work on this repository:

npm install
npm run dev

WordPress

Theia Sticky Sidebar for WordPress

Also available as a premium WordPress plugin that comes with a user-friendly admin panel and supports a plethora of themes out-of-the-box.